Creating a new incident

#1

Hi,

I am trying to create a new incident using the v2 API (see this url: https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents). From everything I see by looking at the API reference, you need the following:

  • API key
  • Service ID
  • Email address

Then you need info about the incident itself (simple enough):

  • Title
  • Details

I am trying to resolve the difference between this and what I see on things like the Jenkins plugin for PagerDuty, which takes the following:

  • Service Integration Key
  • incidentKey
  • Incident Description

Is this plugin using the v1 version of the plugin? (https://v1.developer.pagerduty.com/documentation/events/trigger)

How does the Service Integration Key relate to the the Service ID?

Why is it that you can create an incident with a Service ID using v2 but you need to use an Integration Key for v1?

The reason I ask is I would much prefer to have just a single ID needed (integration key) but I would prefer to use the v2 API.

Thanks
Tom

#2

Hi Tom,

There are actually two types of APIs we provide: the Events API and the REST API. There are also two versions of each of these APIs. The “v1” API you refer to here is the v1 Events API, and the most up-to-date documentation on that API is here:

https://v2.developer.pagerduty.com/docs/events-api

Most integrations use the Events API; you can tell that this is the case if they require an integration key versus a REST API token. In the asynchronous Events API, the integration key is used both as globally-unique identifier and (effectively) as a means of authentication. In the REST API, which is not particular to any service or integration, but permits arbitrary operations on data in PagerDuty, requires an authentication token to be used for authenticating each request.

Based on your interests and requirements, I would suggest checking out the v2 Events API:
https://v2.developer.pagerduty.com/docs/events-api-v2

However, just in case you were looking at using the REST API v2 because you are concerned about the end date for official support of v1 (February 6, 2018, per the FAQ), know that this applies only to the v1 REST API, and there are no plans to end support for the v1 Events API in the foreseeable future. Hence, although you may find it advantageous to use the v2 Events API for its newer features (such as the ability to directly set common event format fields), it should still be safe to use the v1 Events API.